Graphics Plus/Graphics Plus.iso/amiga/modelers/t3d/igensurf.doc

Text File | 1991-09-29 | 14.6 KB | 458 lines

                    igensurf v. 1.0.
                  ====================

1. Introduction:
-----------------

igensurf is a program to generate a TTDDD description of a  functional
surface.   The  TTDDD  description  can  then  be converted to Imagine
object files with the WriteTDDD utility written by Glenn Lewis.

The functional surface is defined by  three  user  supplied  functions
x(s,t),  y(s,t)  and z(s,t) where s and t will be varying from 0 to 1.
The surface normal is defined by the right hand  rule  as  applied  to
(s,t).

It is possible to create a very wide class of objects  with  igensurf.
In  fact, I can't offhand think of an object which couldn't be created
with it (although it often would be much easier to create  the  object
with the Imagine editors).

The language  used  to  define  the  surface  contains  arithmetic  if
statements  and  'switch'  statements  as  well  as a lot of different
mathematical functions. Just to make things more interesting, you also
have access to different noise functions, so that it  is  possible  to
create landscapes etc.

Furthermore igensurf can be used to create  objects  based  on  bezier
patches,  you  can  find  an  example  of  this in 'teapot.cal' in the
examples directory.

You'll need some knowledge of mathematics to use this program.



2. Command options:
--------------------

The igensurf command has a rather complex syntax, but  it  gives  very
good control over the objects you might want to create:

        igensurf [-n name] [-s step_s] [-t step_t]
                 [-C] [-R] [-T] [-S scale_factor] [-p] [-v]
                 [-e expression] [-o output_file] input_file ...

Don't panic, you don't have to use all the options at the same time :-)

Lets have a look at the arguments:

  -n name:
    This defines the name of the created object.
    If the name isn't supplied, the name "IGENSURF" is used.
    It is possible to change  the  name  with  the  #name,  #write  or
    #generate commands (see later).

  -S scale_factor
    This option defines a scale factor  which  is  multiplied  on  the
    functions before the object is generated.

    For instance would

    -e "x(s,t)=s; y(s,t)=t; z(s,t)=0" -S 100

    define a flat square with a side length of 100.

    It is possible to change the scale factor with the #scale command.

  -s step_s
  -t step_t
    Any imagine object (except perfect spheres)  consist  of  lots  of
    triangles.  The  -s  and  -t options define how many triangles the
    object should consist of, and thereby the size of these triangles:

    igensurf varies s from 0 to 1 in steps of 1/step_s, and  varies  t
    from  0  to 1 in steps of 1/step_t. For each step it will create 2
    triangles.  Because of this igensurf will  create  2  *  step_s  *
    step_t triangles.

    The created object will look very faceted if step_s and step_t  is
    small, and will be more smooth if these values are bigger.
    The defaults for these values are 10.

    step_s and step_t is available in expressions and functions. It is
    possible  to  override the values by changing the variables step_s
    and step_t in an expression.

    It is necessary to be careful when selecting values for step_s and
    step_t, otherwise you could end up with an acute case of aliassing
    or digital bouncing as Impulse calls it:

    Lets assume that the functional expression contain the following:

        sin(10 * PI * s)

    In this case, it would be a disaster to use '-s 10'! The reason is
    that the the expression then would be evaluated for s = 0.0,  0.1,
    0.2, ... 1.0.
    As you probably can see, the above expression is 0 for  all  these
    values,  which  probably wasn't what you wanted. In this case, you
    should either change -s  10  to  something  else,  or  modify  the
    equation.

  -C
    It is possible to assign different colors  to  the  faces  of  the
    object; you can do this by defining three functions cr(s,t,x,y,z),
    cg(s,t,x,y,z) and cb(s,t,x,y,z).

    cr defines the amount of red (0.0 to 1.0), cg defines  the  amount
    of green, and cb defines the amount of blue.

    The functions are called with the following arguments:
        s, t   : The current values of s and t.
    x, y, z: The coordinates of the centre of the face.
         BEFORE the scale factor has been applied!

    You  tell  igensurf   to  use  these functions by supplying the -C
    option.  You  could  use  the  command  "#color  on"  to  activate
    computation of colors instead of using the option.

    Here is a simple example:

    Lets presume that you have created  a  file,  test.cal,  with  the
    following lines:

        x(s,t) = 100 * s;
        y(s,t) = 0;
        z(s,t) = 100 * t;
        cr(s,t,x,y,z) = z;
        cg(s,t,x,y,z) = z;
        cb(s,t,x,y,z) = z;

    In this case, the command

        igensurf -s 10 -t 10 -C test.cal

    would result in a flat square which would be black at  the  bottom
    and white at the top.


  -R
    You can assign different reflectance values (r, g and  b)  to  the
    faces  of  the  object  by  using the -R options and supplying the
    functions rr(s,t,x,y,z), rg(s,t,x,y,z) and rb(s,t,x,y,z).
    The command "#refl on" could be used instead of the -R option.

  -T
    You can assign different transmittance values (r, g and b) to  the
    faces  of  the  object  by  using the -T options and supplying the
    functions tr(s,t,x,y,z),  tg(s,t,x,y,z)  and  tb(s,t,x,y,z).
    The command "#trans on" could be used instead of the -T option.


  -p
    As mentioned above, you can smooth the object by increasing step_s
    and/or step_t.  This  will,  however,  create  objects  with  more
    triangles  which  is  costly both in memory and in rendering time.
    Another way to create smooth objects is by giving the  -p  option.
    This  will tell Imagine to use Phong shading on the object.  Phong
    shading normally works very  well,  but  it  doesn't  enhance  the
    objects  silhouette  at all.  Phong shading is cheap in memory and
    rendering time.
    You can also activate phong smoothing with the "#phong on" command.

  -v
    igensurf can be rather slow.   If  you  use  the  -v  option,  the
    program  will  tell you what it is doing, so that you can see that
    it still is working.

  -e expr
    Normally, you will write expressions and functions in a file, and
    supply the filename as an argument to igensurf.
    You may instead define these functions with the -e option.  It is
    legal to specify the -e option more than once.

    Here is a very simple example:

    The options

      -e "x(s,t)=s;y(s,t)=t;z(s,t)=0"

    defines a flat square with a side length of 1.


  -o output_file
    If output_file is given on the command_line, the  output  will  be
    written  to  this  file,  otherwise  the output will be written to
    stdout.

  input_file ...
    If you are using some complex expressions, it  probably  would  be
    easier to create a file containing  these  expressions.  Then  you
    just  have  to  specify  the  name  of  the function file. You may
    specify as many input files as you want.



3. Expressions:
----------------

This  section   describes   the   syntax  and  semantics  of  igensurf
expressions.

A function file can contain comments. Comments are enclosed in { and }.

An expression contains real numbers, variable names,  function  calls,
and the following operators:

                        + - * / ^

Operators  are  evaluated  left  to  right.  Powers  have  the highest
precedence; multiplication and division are evaluated before  addition
and  subtraction.  Expressions  can  be grouped with parentheses.

All values are double precision real.

In addition, variables and functions can be defined  by  the  user.  A
variable definition has the form:

    var = expression;

Any  instance  of  the variable in an expression will be replaced with
its definition. A function definition has the form:

    func(a1,a2,..) = expression;

The expression can contain instances of the function arguments as well
as other variables and functions. Function  names  can  be  passed  as
arguments.  Recursive  functions  can  be  defined  using calls to the
defined function or other functions calling the defined function.

To define a constant expression, simply replace the equals sign  ('=')
with a colon (':') in a definition. Constant expressions are evaluated
only  once,  at  the  time  they  are  defined.  This  avoids repeated
evaluation of expressions whose values never change. All values  in  a
constant  expression must be previously defined, with the exception of
function arguments. Constant function definitions are  useful  because
they  will be replaced by their value in any expression that uses them
with constant arguments. All predefined functions and  variables  have
the  constants  attribute.  Thus "sin(PI/4)" in an expression would be
immediately replaced by ".707108" unless sin() or PI were redefined by
the user.

The  following  library  of  predefined  functions  and  variables  is
provided:

step_s
    The value of step_s supplied with the -s  option  on  the  command
    line. You may change step_s if you want.

step_t
    The value of step_t supplied with the -t  option  on  the  command
    line. You may change step_t if you want.

PI
    The ratio of a circle's circumference to its diameter.

if(cond,then,else)
    if 'cond' is greater than zero,  'then'  is  evaluated,  otherwise
    'else'  is  evaluated. This function is is necessary for recursive
    definitions.

select(N,a1,a2,..)
    return  aN  (N  is  rounded to the nearest integer). This function
    provides array capabilities. If N is zero, the number of available
    arguments is returned.

rand(x)
    Compute a random number between 0 and 1 based on x.

floor(x)
    Return largest integer not greater than  x.

ceil(x)
    Return smallest integer not less than x.

sqrt(x)
    Return square root of x.

exp(x)
    Compute e to the power of x.

log(x)
    Compute the logarithm of x to the base e.

log10(x)
    Compute the logarithm of x to the base 10.

sin(x), cos(x), tan(x)
    Trigonometric functions.

asin(x), acos(x), atan(x)
    Inverse trigonometric functions.

atan2(y,x)
    Inverse tangent of y/x (range -PI to PI).

hermite(P1, P2, P3, P4, t)
    The 1-dimensional hermite polynomium.

bezier(P1, P2, P3, P4, t)
    The 1-dimensional bezier function.

bspline(P1, P2, P3, P4, t)
    The 1-dimensional b-spline function.

noise3(x, y, z)
    The 3-dimensional noise function (-1 to 1).

noise3a(x, y, z)
    The X slope of the noise function (-1 to 1).

noise3b(x, y, z)
    The Y slope of the noise function (-1 to 1).

noise3c(x, y, z)
    The Z slope of the noise function (-1 to 1).

fnoise3(x, y, z)
    The fractal noise function (-1 to 1).

4. Commands
------------
It is possible to control igensurf by  using  commands  in  the  input
files.

You can use commands to name objects, add surfaces to objects, start a
new object,  control  surface  smoothing  and  to  activate/deactivate
color, reflectance or transmittance computation.

A command has the form:

    #command arguments

Commands must start in column 1, and must be placed on a separate line.

The following commands are available:

#name [object_name]
    Give new objects the name 'object_name'.

#add
    Compute the surface, and add it to the current object.

    igensurf will execute an #add command before stopping, if  you
        didn't issue an #add command anywhere in the input.

#write [object_name]
    Write the current object to the TTDDD file  and  start  a  new
        object.  If object_name is specified, the object will be given
        this name.
        igensurf will execute a #write command before stopping, if the
        current object hasn't been written to the output file.

#generate [object_name]
    Compute the surface, and add it to the current  object.   Then
        write it to the TTDDD file.
    This is exactly the same as:
        #add             followed by
        #write [object_name]

#scale scale_factor
    Change the scale factor to 'scale_factor'.

#phong [on|off]
#smooth [on|off]
    Activate/Deactivate phong smoothing.

#color [on|off]
    Activate/deactivate generation of face color info.
    This  will  only  work  if  you  have  defined  the  functions
        cr(s,t,x,y,z), cb(s,t,x,y,z) and cg(s,t,x,y,z).

#refl [on|off]
    Activate/deactivate generation of face reflectance info.
    This  will  only  work  if  you  have  defined  the  functions
        cr(s,t,x,y,z), rb(s,t,x,y,z) and rg(s,t,x,y,z).

#trans [on|off]
    Activate/deactivate generation of face transmittance info.
    This  will  only  work  if  you  have  defined  the  functions
        tr(s,t,x,y,z), tb(s,t,x,y,z) and tg(s,t,x,y,z).

5. Examples:
-------------

You can find some example files in "examples" directory.

Here is a list of the examples:

curtain.cal
    Demonstrates how to use the noise functions to modify  a  surface.
    The  resulting  object is something which should look a little bit
    as a curtain:-)

hyper.cal
    Functions used to create a hyperboloid.

mountain.cal
    Demonstrates how to apply colors to a surface.

sphere.cal
    Functions used to create a sphere. This is much easier  done  from
    within Imagine!

spiral1.cal
    Creates some sort of spiral.

spiral2.cal
    Creates another spiral.

super_el.cal
    Creates a superellipsoid. Have a look at  this  example,  you  can
    create a lot of different objects by varying a few parameters.

util.cal
    This file contain some function definitions, which could be useful
    when playing with igensurf.

teapot.cal + bpatch.cal
    These files show how to use igensurf to create an object based  on
    bezier  patch  data. This is the most complex example of them all.
    It also show how to group surfaces together into 1 or more objects.

vase.cal
    Creates a vase.

wastebasket.cal
    Creates a wastebasket without bottom!

wave.cal
    Create a wave.

All the examples should hopefully be self explanatory.

I've found, that just entering some equations and running the  program
sometimes  lead  to  interesting objects; as the people at Impulse say
all the time:

        Experiment, experiment, experiment... :-)


6. Credits:
------------

igensurf is written by Helge E. Rasmussen ([e-mail]). It is based
on code written by Greg Ward for the Radiance synthetic imaging system.

writetddd, which is needed if you want to use this program, is written
by Glenn Lewis ([e-mail]), and is a shareware product.

You may use the program and the source code in any  way  you  want  as
long  as  you  do  not resell the software as your own, or use it in a
commercial product.

Please  let  me  know  if  you  find  any  bugs,  or  have  ideas  for
enhancements.

Helge E. Rasmussen